home *** CD-ROM | disk | FTP | other *** search
/ Gigarom 1 / Gigarom Macintosh Archives (Quantum Leap)(CDRM1080320)(1993).iso / FILES / COP / A-M / Extra Translators 4 SD.sea / Translator Documentation / About btoa_atob Translator < prev    next >
Text File  |  1991-01-06  |  11KB  |  304 lines
  1. btoa/atob Translator for StuffIt Deluxe
  2.  
  3. Version 1.0.1 of 91.01.06.
  4.  
  5. Written by Raymond Lau
  6.  
  7. Copyright (C) 1990, Raymond Lau.  All Rights Reserved.
  8.  
  9.  
  10. This software is being licensed to you free of cost.
  11.  
  12. Please see Terms of usage and distribution at the end
  13. of this document for information regarding your right
  14. to use and distribute this software.
  15.  
  16.  
  17.  
  18. Introduction:
  19.  
  20. btoa/atob Translator is an external translator for use
  21. with StuffIt Deluxe, available from Aladdin Systems, Inc.,
  22. Deer Part Center, #23A-171, Aptos, CA 95003-4723.
  23. This translator provided compatibility with the UNIX filters
  24. "btoa" and "atob."
  25.  
  26. btoa and atob are UNIX filters which convert 8 bit binary
  27. data to 7 bit ASCII data for transmission across channels
  28. which only support 7 bit ASCII data.  For example, you can
  29. only email 7 bit ASCII data with SMTP.  btoa/atob performs
  30. the same function as uuencode/uudecode in the UNIX world but
  31. more efficiently, encoding 4 bytes into 5 instead of 3 into 4.
  32. BinHex4 on the Mac performs a similar function.
  33.  
  34. Why use btoa/atob instead of other similar utilities?
  35.      1. btoa/atob is the most effective ASCII encoder
  36.         compatible with UNIX SMTP mailers that I know of.
  37.      2. btoa/atob is compatible with the encoding used
  38.         by the popular "tarmail" script.
  39. Why use something OTHER than btoa/atob?
  40.      1. With the MacBinary option built into this translator,
  41.         you can transfer entire Macintosh files, including
  42.         applications, as 7 bit ASCII data.  However, the
  43.         protocol provided here is not as of this writing
  44.         an accepted standard whereas BinHex4 is for this
  45.         purpose.  Also, BinHex4 provides better error
  46.         detection.  However, the error detection in
  47.         btoa/atob is reasonably sound.
  48.  
  49.  
  50. Installation:
  51.  
  52. The rest of this documentation assumes that you have properly
  53. installed StuffIt Deluxe and are familiar with the operation
  54. of StuffIt Deluxe.
  55.  
  56. To install this translator, placed it in the Translators
  57. folder in the System folder of your startup drive.  Then
  58. launch (or quit and relaunch, as appropriate) StuffIt Deluxe.
  59.  
  60. If you are in Standard menu mode, you must switch to Expert
  61. menu mode to use this translator.
  62.  
  63.  
  64. Operation:
  65.  
  66. After installation, you should have a new choice under the
  67. Other menu with the name "btoa/atob."  This item has
  68. 2 subitems.  The subitems are Binary to ASCII... and ASCII
  69. to Binary...
  70.  
  71. To convert a binary file to ASCII, select Binary to ASCII.
  72. At the bottom of the dialog should be a checkbox labelled
  73. "Make MacBinary."  If you are encoding a "Macintosh" file,
  74. you should have this checked.  Doing so will cause the
  75. translator to first convert your file to MacBinary format
  76. before doing btoa translation.  If you only wish to encode
  77. the data fork of a file, without saving information about
  78. the file such as its type/creator, then uncheck this.
  79.  
  80.    Example:  You want to email an application to your friend.
  81.              Check Make MacBinary.
  82.              You have a binary PostScript file and want to
  83.              email it to a distant location for printing
  84.              from a UNIX printer server.  Uncheck Make
  85.              MacBinary.
  86.  
  87.    Note:     The MacBinary encoding is compatible with the
  88.              mbget/mbput filters.
  89.  
  90. To convert an encoded ASCII file to a binary file, select
  91. ASCII to Binary.  Normally, you should keep Recognize
  92. MacBinary checked.  The translator will know when a file
  93. being decoded has been MacBinary encoded and when it hasn't.
  94. However, if you know the file was not from a Macintosh
  95. source (or that it wasn't MacBinary encoded), then keep this
  96. unchecked.  The MacBinary header does not have rigorous
  97. presence indicators built into it so non-MB encoded files may
  98. be mistaken for MB encoded files.
  99.  
  100.  
  101. Changes from 1.0 to 1.0.1:
  102.  
  103. When decoding non-MacBinary files whose size is not a multiple
  104. of 4, extra null padding inserted by the encoder was not
  105. stripped properly, resulting in an error and an extra 1-3 null
  106. bytes at the end of file.
  107.  
  108. When an error occurs, the beach ball was not stopped from
  109. spinning.
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116. Appendix A: Excerpts from man page for the btoa/atob filters.
  117.  
  118. NAME: btoa, atob, tarmail, untarmail encode/decode binary to
  119.       printable ASCII
  120.  
  121. SYNOPSIS: btoa < inbinary > outtext
  122.           atob < intext > outbinary
  123.           tarmail who subject files ...
  124.  
  125. DESCRIPTION: btoa is a filter that reads anything from the
  126.              standard input, and encodes it into printable ASCII
  127.              on the standard output.  It also attaches checksum
  128.              information used by the reverse filter "atob" to
  129.              check integrity.  atob gives NO output (and exits
  130.              with an error message) if its input is garbage or the
  131.              checksums do not check.
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. Appendix B: Terms of usage and distribution:
  140.  
  141. Although copyrighted, this software is being licensed 
  142. to you for your use free of charge.  However, ownership
  143. of and interest in this software shall remain with the
  144. author.  Use and distribution of this software is
  145. governed by the following terms in an effort to
  146. reasonably insure that this software will remain
  147. freely available and that no one other than the author
  148. will derive a commercial benefit from distributing
  149. this software.
  150.  
  151.  
  152. LICENSE AGREEMENT
  153.  
  154.  
  155. "You," "your," and the "user" refers to any person or
  156. entity which acquires or uses this software.
  157.  
  158. "Software" refers to any computer programs identified
  159. at the start of this documentation file, together with
  160. all codes, techniques, software tools, formats, designs,
  161. concepts, methods, ideas, and documentation assoicated
  162. with the computer program(s).  The term also includes
  163. all copies of any part of the software and documentation.
  164.  
  165. "Author" refers to the author of this software, Raymond
  166. Lau.
  167.  
  168.  
  169. This software is owned by the author and contains
  170. valuable and proprietary information of the author's.
  171. If you violate any part of this agreement, your right
  172. to use this software terminates automatically.  In the
  173. event of termination of this agreement, you must destroy
  174. all copies of this software and derivatives of this
  175. software in your possession and cease distributing the
  176. same.
  177.  
  178. This software is being licensed to you as provided by
  179. the terms of this agreement.
  180.  
  181. You may:
  182.    1. Use this software on as many computers
  183.       as you want at any given time.
  184.    2. Make as many backup copies of this software as
  185.       you want.
  186.    3. Alter the software in any manner you see fit
  187.       FOR YOUR OWN PERSONAL USE.  Such altered versions
  188.       should not be distributed.  The creation of
  189.       such derivatives shall not diminish the author's
  190.       title to this software.
  191.    4. Terminate this agreement at any time by destroying
  192.       all copies of this software and derivatives of
  193.       this software and cease distributing the same.
  194.  
  195. You may not:
  196.    1. Create any derivative works from this software
  197.       for distribution.
  198.    2. Reverse engineer, disassemble, decompile, or
  199.       otherwise attempt to discover the source code to
  200.       this software.
  201.    3. Use this software in any manner as to discover
  202.       proprietary information relating to the Translator
  203.       interface in StuffIt Deluxe and/or StuffIt Classic.
  204.  
  205.  
  206. You may distribute this software provided that:
  207.    1. This software is distributed free of any charges
  208.       except as provided for under 1a.  This software may
  209.       not be sub-licensed, sold, lent, rented, or leased
  210.       except as provided for under 1a.
  211.           1a. You may charge a nominal fee to cover
  212.               duplication, shipping and/or handling costs
  213.               of distributing this software provided that
  214.               the pro-rata fee (ex: the fee of ordering a
  215.               disk/CD/tape/etc divided by the number of 
  216.               programs on it) does not exceed US $1.  You
  217.               may include this software in any compilation
  218.               even if you sell the compilation for a
  219.               profit provided that the pro-rata fee defined
  220.               above does not exceed US $1 for this software.
  221.  
  222.               You may also charge your usual timesharing,
  223.               network usage and/or membership fee if you
  224.               distribute this software electronically.
  225.  
  226.               While you may claim a compilation copyright
  227.               on any compilations which include this
  228.               software, interest in and ownership of this
  229.               software shall remain with the author.
  230.             
  231.    2. You include this documentation file with the
  232.       distribution.
  233.    3. You do not modify either this documentation file
  234.       or the software itself.
  235.    4. You do not use the name of this software or
  236.       of the author or the fact that you provide this
  237.       software in any promotional material relating
  238.       to your distribution of this software.  However, you
  239.       may include such information in a catalog listing of
  240.       your offerings.
  241.    5. You may not transfer this software in a manner as
  242.       to violate any regulations relating to the transfer
  243.       of software, including the US Export Administration
  244.       Act.
  245.  
  246. Disclaimer of warranty:
  247.  
  248. In using this software, you understand and agree that this
  249. software is provided "as is" without warranty of any kind.
  250. The entire risk as to the results and performance of using
  251. this software lies entirely with you, the user.  The author
  252. does not make any warranties, either expressed or implied,
  253. including but not limited to implied warranties of
  254. merchantability and fitness for a particular purpose, with
  255. respect to this software.
  256.  
  257. In no event shall the author be liable for any consequential,
  258. incidental, or special damages whatsoever (including without
  259. limitation damages for loss of critical data, loss of profits,
  260. interruption of business, and the like) arising out of the
  261. use or inability to use this software.  Because some states
  262. do not allow the exclusion or limitation of liability for
  263. consequential or incidental damages, the above limitations
  264. may not apply to you.
  265.  
  266. Although the author would appreciate any feedback and bug
  267. reports, the author shall not be responsible for correcting
  268. any problems which you discover or otherwise help you
  269. maintain and use this software.  Furthermore, the author
  270. may at any time replace, modify, alter, improve, enhance
  271. or change this software.
  272.  
  273.  
  274. Complete agreement:
  275.  
  276. This agreement constitues the entire agreement and supersedes
  277. any prior agreements between you and the author concerning
  278. this software.  This agreement cannot be amended, modified,
  279. or waived except in writing.
  280.  
  281. General:
  282.  
  283. If any provision of this agreement shall be found to be
  284. unenforcible, it shall be deemed severed from the remainder
  285. of this agreement.
  286.  
  287. This agreement shall be construed in accordance with the laws
  288. of the State of New York.  Any arbitration or litigation
  289. relating to this agreement shall take place in the State of
  290. New York.
  291.  
  292.  
  293.  
  294. U.S. GOVERNMENT RESTRICTED RIGHTS
  295.  
  296. This Software is provided with RESTRICTED RIGHTS.  Use,
  297. duplication, or disclosure by the government is subject to
  298. restrictions set forth in subparagraph (c)(1)(ii) of the
  299. Rights in Technical Data and Computer Software clause at
  300. 48 CFR 252.227-7013, or in subparagraphs (a) through (d) of
  301. the Commercial Computer Software Restricted Rights clause at
  302. 48 CFR 52.227-19, as applicable.  The contractor/manufacturer
  303. is Raymond Lau, 100-04 70 Ave., Forest Hills, NY 11375-5133.
  304.